package lucee.runtime.ai;

import java.util.List;

/**
 * The Response interface defines methods for accessing results from an AI service inquiry.
 * <p>
 * This interface provides access to both simple text responses and multipart responses that may
 * contain different content types, along with metadata about the computational resources consumed
 * during processing.
 */
public interface Response {

	/**
	 * Returns the total number of tokens used in processing this response.
	 * <p>
	 * Tokens are the basic units of text processing for many AI models, roughly corresponding to word
	 * fragments. This count typically includes tokens from both the input message and the generated
	 * response, and may be used for monitoring resource usage or billing purposes.
	 *
	 * @return long value representing the total token count consumed
	 */
	public long getTotalTokenUsed();

	/**
	 * Returns the primary textual answer generated by the AI service.
	 * <p>
	 * This method retrieves the main text response returned by the AI model. For backward compatibility
	 * with text-only responses, this returns the content of the first text part in a multipart
	 * response.
	 *
	 * @return String containing the AI-generated answer, or null if no text response exists
	 */
	public String getAnswer();

	/**
	 * Returns all response parts from the AI service.
	 * <p>
	 * This method provides access to all content parts in the response, which may include text, images,
	 * audio, structured data, or other content types. For a simple text-only response, this list will
	 * contain a single text part.
	 *
	 * @return List of ResponsePart objects representing all content in the response
	 */
	public List<Part> getAnswers();

	/**
	 * Indicates whether this response contains multiple parts with different content.
	 * <p>
	 * This method helps distinguish between simple text-only responses and more complex responses that
	 * may contain multiple content types or sections.
	 *
	 * @return boolean indicating whether this is a multipart response
	 */
	public boolean isMultiPart();
}